package com.yc.cloud.admin.service;

import com.yc.cloud.admin.dto.request.FaceAddFileReqDTO;
import com.yc.cloud.admin.dto.request.FaceDetectReqDTO;
import com.yc.cloud.admin.dto.response.FaceAddFileRespDTO;
import com.yc.cloud.admin.dto.response.FaceDetectRespDTO;
import org.springframework.web.multipart.MultipartFile;

import java.io.File;

/**
 * 人脸识别服务接口
 *
 * @author JackGu
 * @since 2025-11-05
 */
public interface FaceRecognitionService {

    /**
     * 人脸检测
     *
     * @param reqDTO 请求参数
     * @return 检测结果
     */
    FaceDetectRespDTO detectFace(FaceDetectReqDTO reqDTO);

    /**
     * 添加人脸文件（使用MultipartFile）
     *
     * @param file 人脸图片文件
     * @param reqDTO 请求参数（包含personId、personName、metaInfo）
     * @return 添加结果
     */
    FaceAddFileRespDTO addFaceFile(MultipartFile file, FaceAddFileReqDTO reqDTO);

    /**
     * 添加人脸文件（使用File）
     *
     * @param file 人脸图片文件
     * @param reqDTO 请求参数（包含personId、personName、metaInfo）
     * @return 添加结果
     */
    FaceAddFileRespDTO addFaceFile(File file, FaceAddFileReqDTO reqDTO);

    /**
     * 人脸比对（通过图片Base64）
     *
     * @param imageBase64 待比对的图片Base64编码
     * @param faceId 已存储的人脸ID
     * @param threshold 相似度阈值（0-1），默认0.6
     * @return 比对结果
     */
    FaceDetectRespDTO compareFace(String imageBase64, String faceId, Float threshold);

    /**
     * 人脸比对（通过文件）
     *
     * @param file 待比对的图片文件
     * @param faceId 已存储的人脸ID
     * @param threshold 相似度阈值（0-1），默认0.6
     * @return 比对结果
     */
    FaceDetectRespDTO compareFaceByFile(MultipartFile file, String faceId, Float threshold);

    /**
     * 删除人脸
     *
     * @param faceId 人脸ID
     * @return 是否删除成功
     */
    Boolean deleteFace(String faceId);

    /**
     * 查询人脸是否存在
     *
     * @param faceId 人脸ID
     * @return 是否存在
     */
    Boolean existsFace(String faceId);

    /**
     * 人脸搜索（通过文件）- 在人脸库中搜索最匹配的人脸
     *
     * @param file 待搜索的图片文件
     * @param threshold 相似度阈值（0-1），默认0.6
     * @param topK 返回前K个匹配结果，默认1
     * @return 搜索结果
     */
    com.yc.cloud.admin.dto.response.FaceSearchRespDTO searchFaceByFile(MultipartFile file, Float threshold, Integer topK);

    /**
     * 人脸搜索（通过Base64）- 在人脸库中搜索最匹配的人脸
     *
     * @param imageBase64 待搜索的图片Base64编码
     * @param threshold 相似度阈值（0-1），默认0.6
     * @param topK 返回前K个匹配结果，默认1
     * @return 搜索结果
     */
    com.yc.cloud.admin.dto.response.FaceSearchRespDTO searchFace(String imageBase64, Float threshold, Integer topK);
}

